Web API Common Features
Some aspects of the Web API
A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. request and response formats are consistent across all endpoints. This includes a small set of HTTP headers, HTTP statuses returned by the server for successful requests, and various error conditions. Common request headers are given in Table 65: Common Request Headers, common response headers (for successful requests and certain unsuccessful requests) are given in Table 66: Common Response Headers, and HTTP statuses are given in Table 67: HTTP Statuses.
By default, all Keyfactor API A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. methods start with a base path, which corresponds to an application under IIS; this path is configurable at install time. For the Keyfactor API, the default base path is KeyfactorApi. The API component name and method name then comprise the parts of the URL, each separated by a forward slash. For example, “/KeyfactorApi/Certificates/Import” would be the URL format for the Import method of the Certificates component in the Keyfactor API.
Table 65: Common Request Headers
|
Header Name |
API Version |
Header Value |
Description |
|---|---|---|---|
|
Content-Type |
Both |
application/json OR application/xml |
POST methods use application/json. When application/xml is needed, it is specifically indicated on the endpoint page. |
|
Accept |
Both |
application/json; charset=utf-8 |
Most methods returning complex values will use this content type. |
|
Authorization |
Both |
Basic <base-64 DOMAIN\user:pass> |
In most cases, Web API clients will use Basic authentication over SSL/TLS. |
|
Host |
Both |
<Keyfactor Command server hostname> |
Address of Keyfactor Command server. Automatically generated in most clients. |
|
Content-Length |
Both |
Request length in bytes |
Optional, but automatically generated by most clients. |
|
X-Keyfactor-Requested-With |
Both |
XMLHttpRequest |
This is mandatory to send in a request to the Keyfactor API on POSTs, PUTs, and DELETEs, and the value is case sensitive. This is for security. |
| X-Keyfactor-API-Version | Keyfactor API | 1 or 2 | Desired version of the endpoint. If not provided, this defaults to version 1. |
Table 66: Common Response Headers
|
Header Name |
API Version |
Header Value |
Description |
|---|---|---|---|
|
Cache-Control |
Both |
no-cache |
API requests are generally not cacheable. Note that this is not respected by all client systems. |
|
Pragma |
Both |
no-cache |
API requests are generally not cacheable. Note that this is not respected by all client systems. |
|
Content-Length |
Both |
<varies> |
Length of the HTTP response. |
|
Content-Type |
Both |
application/json |
Most calls return application/json, but occasionally text/plain or text/xml. |
|
Expires |
Both |
-1 |
Usually ignored. |
|
Server |
Both |
<varies> |
Software version reported by IIS platform hosting Keyfactor Command. |
| X-Keyfactor-Product-Version | Keyfactor API | <varies> | Keyfactor Command platform version. |
|
X-Total-Count |
Keyfactor API |
<varies> |
Total number of elements returned. |
|
X-AspNet-Version |
Both |
<varies> |
Version of ASP.NET supporting Keyfactor Command installation. |
|
X-Powered-By |
Both |
ASP.NET |
Header added by underlying ASP.NET implementation. |
|
Date |
Both |
<varies> |
Timestamp of the HTTP response. |
|
Number/Name |
Description |
|---|---|
|
200 OK |
Request successful; results in response body |
|
204 No Content |
Request successful; no content in response body |
|
400 Bad Request |
Malformed or invalid data; additional information may be available in the response body and/or Keyfactor Command server logs |
|
401 Unauthorized |
Invalid credentials (user unauthenticated) |
|
403 Forbidden |
Can often indicate that the credentials map to a user without permissions for this action in Keyfactor Command (user unauthorized) |
|
404 Page not Found |
Invalid request path |
|
500 Internal Server Error |
Keyfactor Command encountered an unexpected error attempting to handle the request. See response body and Keyfactor Command server logs for details. |
|
502 Bad Gateway |
Keyfactor Command attempted to contact a CA or other upstream server to process the request, but was unable to. See Keyfactor Command server logs for details. |
